---
title: OpenAI Agents SDK TypeScript
description: The OpenAI Agents SDK for TypeScript enables you to build agentic AI apps in a lightweight, easy-to-use package with very few abstractions.
---

import { LinkCard } from '@astrojs/starlight/components';
import { Code } from '@astrojs/starlight/components';
import Hero from '../../../components/Hero.astro';

import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw';

<Hero>
  <Fragment slot="title">快速上手</Fragment>
  <Fragment slot="description">几分钟内构建您的第一个智能体。</Fragment>
  <Fragment slot="cta">开始构建</Fragment>
</Hero>

## 概述

[适用于 TypeScript 的 OpenAI Agents SDK](https://github.com/openai/openai-agents-js)
让你以轻量、易用、抽象最少的方式构建具备智能体能力的 AI 应用。它是我们之前
面向智能体的实验项目
[Swarm](https://github.com/openai/swarm/tree/main) 的面向生产的升级版本，并且[也可用于 Python](https://github.com/openai/openai-agents-python)。Agents SDK 仅包含一小组基础组件：

- **智能体（Agents）**：配备 instructions 和 tools 的 LLM
- **交接（Handoffs）**：允许智能体将特定任务委派给其他智能体
- **护栏（Guardrails）**：用于对传入智能体的输入进行校验

结合 TypeScript，这些基础组件足以表达工具与智能体之间的复杂关系，帮助你在没有陡峭学习曲线的情况下构建真实世界的应用。此外，SDK 内置 **追踪（tracing）**，便于可视化与调试你的智能体流程，还可以对其进行评估，甚至为你的应用微调模型。

## 为何使用 Agents SDK

该 SDK 的两大设计原则：

1. 功能足够丰富，值得使用；但基础组件足够精简，便于快速上手。
2. 开箱即用体验优秀，同时又可精确自定义具体行为。

SDK 的主要特性包括：

- **Agent loop**：内置智能体循环，负责调用工具、将结果返回给 LLM，并循环直至 LLM 完成。
- **TypeScript 优先**：使用内建语言特性来编排与串联智能体，而无需学习新的抽象。
- **交接（Handoffs）**：在多个智能体之间进行协调与委派的强大能力。
- **护栏（Guardrails）**：与智能体并行运行输入校验与检查，如检查失败可提前中止。
- **函数工具（Function tools）**：将任意 TypeScript 函数变为工具，自动生成模式（schema）并提供基于 Zod 的校验。
- **追踪（Tracing）**：内置追踪，用于可视化、调试和监控你的工作流，并可使用 OpenAI 的评估、微调与蒸馏工具。
- **实时智能体（Realtime Agents）**：构建强大的语音智能体，包含自动打断检测、上下文管理、护栏等。

## 安装

```bash
npm install @openai/agents zod@3
```

## Hello World 示例

<Code lang="typescript" code={helloWorldExample} title="Hello World" />

（运行本示例时，请确保已设置 `OPENAI_API_KEY` 环境变量）

```bash
export OPENAI_API_KEY=sk-...
```
